---
id: props
title: Props
sidebar_label: Getting Started
description: The react-native-reanimated-carousel props guide. 📖
keywords:
  - react-native-reanimated-carousel
  - reanimated-carousel
  - reanimated carousel
  - react-native
  - snap-carousel
  - react native
  - snap carousel
  - ios
  - android
  - carousel
  - snap
  - reanimated
image: 
slug: /props
---

# Props
---

import { Callout } from 'nextra/components'

## Basic

<Callout emoji="🙋‍♂️">
Basically, each props should have a corresponding example, which is more intuitive, but due to time constraints, it has not been done for the time being. It is expected that someone can contribute to submit PR.
</Callout>

### `data`

Carousel items data set

| type   | default | required |
| ------ | ------- | -------- |
| T[] | -     | ✅      |

### `renderItem`

Render carousel item

| type   | default | required |
| ------ | ------- | -------- |
| \(info: \{ item: T, index: number, animationValue: SharedValue\<number\> \}\) =\> React.ReactElement | -     | ✅      |

### `defaultScrollOffsetValue`

The default animated value of the carousel.

| type   | default | required |
| ------ | ------- | -------- |
| useSharedValue\<number\>\(0\) | -     | ❌      |

### `autoFillData`

Auto fill data array to allow loop playback when the loop props is true.\(\[1\] \=\> \[1, 1, 1\]；\[1, 2\] \=\> \[1, 2, 1, 2\]\)

| type   | default | required |
| ------ | ------- | -------- |
| boolean | true     | ❌      |

### `vertical`

Layout items vertically instead of horizontally

| type   | default | required |
| ------ | ------- | -------- |
| boolean | false     | ❌      |

### `width`

Specified carousel item width

| type   | default | required |
| ------ | ------- | -------- |
| number \| undefined | '100%'     | ❌      |

### `height`

Specified carousel item height

| type   | default | required |
| ------ | ------- | -------- |
| number \| undefined | '100%'     | ❌      |

### `mode`

Carousel Animated transitions

| type   | default | required |
| ------ | ------- | -------- |
| 'horizontal-stack'\|'vertical-stack'\|'parallax' | default     | ❌      |

### `modeConfig`

Different modes correspond to different configurations. For details, see below\[modeConfig\]\(#`modeConfig` Props\)

| type   | default | required |
| ------ | ------- | -------- |
| \{moveSize\?: number;stackInterval\?: number;scaleInterval\?: number;rotateZDeg\?: number;snapDirection\?: 'left' \| 'right';\} | -     | ❌      |

### `style`

Carousel container style

| type   | default | required |
| ------ | ------- | -------- |
| ViewStyle | \{\}     | ❌      |

### `defaultIndex`

Default index

| type   | default | required |
| ------ | ------- | -------- |
| number | 0     | ❌      |

### `autoPlay`

Auto play

| type   | default | required |
| ------ | ------- | -------- |
| boolean | false     | ❌      |

### `autoPlayReverse`

Auto play reverse playback

| type   | default | required |
| ------ | ------- | -------- |
| boolean | false     | ❌      |

### `autoPlayInterval`

Auto play playback interval

| type   | default | required |
| ------ | ------- | -------- |
| number | 1000     | ❌      |

### `scrollAnimationDuration`

Time a scroll animation takes to finish

| type   | default | required |
| ------ | ------- | -------- |
| number | 500     | ❌      |

### `loop`

Carousel loop playback

| type   | default | required |
| ------ | ------- | -------- |
| boolean | true     | ❌      |

### `testID`

Used to locate this view in end-to-end tests

| type   | default | required |
| ------ | ------- | -------- |
| string | -     | ❌      |

### `onSnapToItem`

Callback fired when navigating to an item

| type   | default | required |
| ------ | ------- | -------- |
| \(index: number\) => void | -     | ❌      |

### `onScrollStart`

Callback fired when scroll start

| type   | default | required |
| ------ | ------- | -------- |
| \(\) => void | -     | ❌      |

### `onScrollEnd`

Callback fired when scroll end

| type   | default | required |
| ------ | ------- | -------- |
| \(index: number\) => void | -     | ❌      |

### `withAnimation`

Specifies the scrolling animation effect

| type   | default | required |
| ------ | ------- | -------- |
| \{type: 'spring';config: WithSpringConfig;\} \| \{type: 'timing';config: WithTimingConfig;\} | -     | ❌      |

### `onConfigurePanGesture`

PanGesture config

| type   | default | required |
| ------ | ------- | -------- |
| onConfigurePanGesture?: \(panGesture: PanGesture\) => void | -     | ❌      |

### `windowSize`

The maximum number of items that can respond to pan gesture events, `0` means all items will respond to pan gesture events

| type   | default | required |
| ------ | ------- | -------- |
| number | 0     | ❌      |

### `onProgressChange`

This callback is called when the carousel is scrolled. If you want to update a shared value automatically, you can use the shared value as a parameter directly.
The callback provides two parameters: `offsetProgress`:Total of offset distance \(0 390 780 ...\); `absoluteProgress`:Convert to index \(0 1 2 ...\)

| type   | default | required |
| ------ | ------- | -------- |
| onProgressChange?: \(offsetProgress: number,absoluteProgress: number\) => void | -     | ❌      |

### `modeConfig`

Stack layout animation style

| type   | default | required |
| ------ | ------- | -------- |
| \{moveSize\?: number;stackInterval\?: number;scaleInterval\?: number;rotateZDeg\?: number;snapDirection\?: 'left' \| 'right';\} | \{ snapDirection: 'left',moveSize: window.width,stackInterval: 30,scaleInterval: 0.08,rotateZDeg: 135\}     | ❌      |

### `pagingEnabled`

When true, the scroll view stops on multiples of the scroll view's size when scrolling

| type   | default | required |
| ------ | ------- | -------- |
| boolean | true     | ❌      |

### `overscrollEnabled`

If enabled, the item will scroll to the first placement when scrolling past the edge rather than closing to the last. (previous conditions: loop=false)

| type   | default | required |
| ------ | ------- | -------- |
| boolean | true     | ❌      |

### `snapEnabled`

If enabled, releasing the touch will scroll to the nearest item, valid when pagingEnabled=false

| type   | default | required |
| ------ | ------- | -------- |
| boolean | true     | ❌      |

### `enabled`

when false, Carousel will not respond to any gestures

| type   | default | required |
| ------ | ------- | -------- |
| boolean | true     | ❌      |

### `fixedDirection`

If positive, the carousel will scroll to the positive direction and vice versa.

| type   | default | required |
| ------ | ------- | -------- |
| 'positive' \| 'negative | -     | ❌      |

### `customConfig`

Custom carousel config

| type   | default | required |
| ------ | ------- | -------- |
| \(\) => \{type\?: 'negative' \| 'positive';viewCount\?: number;} | -     | ❌      |

### `customAnimation`

Custom animations. For details, see below\[custom animation\]\(.\/custom-animation.md\)

| type   | default | required |
| ------ | ------- | -------- |
| \(value: number\) => ViewStyle | -     | ❌      |

### `maxScrollDistancePerSwipe`

Maximum offset value for one scroll. Carousel cannot scroll over than this value.

| type   | default | required |
| ------ | ------- | -------- |
| number | -     | ❌      |

### `minScrollDistancePerSwipe`

Minimum offset value for once scroll. If the translation value is less than this value, the carousel will not scroll.

| type   | default | required |
| ------ | ------- | -------- |
| number | -     | ❌      |

## Parallax Mode

```tsx copy
<Carousel
    {...restProps}
    mode="parallax"
    modeConfig={{
        parallaxScrollingScale: 0.9,
        parallaxScrollingOffset: 50,
        parallaxAdjacentItemScale: 0.8,
    }}
/>
```

### `parallaxScrollingOffset`

control prev/next item offset

| type   | default | required |
| ------ | ------- | -------- |
| number | 100     | ❌      |

### `parallaxScrollingScale`

control prev/current/next item scale

| type   | default | required |
| ------ | ------- | -------- |
| number | 0.8     | ❌      |

### `parallaxAdjacentItemScale`

control prev/next item scale

| type   | default | required |
| ------ | ------- | -------- |
| number | parallaxAdjacentItemScale \|\| Math.pow\(parallaxScrollingScale, 2\)     | ❌      |

## Stack Mode

```tsx copy
<Carousel
    {...restProps}
    mode="stack"
    modeConfig={{
        moveSize: 200,
        stackInterval: 30,
        scaleInterval: 0.08,
        rotateZDeg: 135,
        snapDirection: 'left',
    }}
/>
```

### `stackInterval`

The spacing of each item

| type   | default | required |
| ------ | ------- | -------- |
| number | 18     | ❌      |

### `moveSize`

Item translate size

| type   | default | required |
| ------ | ------- | -------- |
| number | screen.width     | ❌      |

### `scaleInterval`

The scale of each item

| type   | default | required |
| ------ | ------- | -------- |
| number | 0.04     | ❌      |

### `opacityInterval`

The opacity of each item

| type   | default | required |
| ------ | ------- | -------- |
| number | 0.1     | ❌      |

### `rotateZDeg`

The item rotation Angle

| type   | default | required |
| ------ | ------- | -------- |
| number | 30     | ❌      |

### `snapDirection`

Slide direction

| type   | default | required |
| ------ | ------- | -------- |
| 'left'\|'right' | 'left'     | ❌      |


## Ref

By using these methods, remember you need to reference the component using [React useRef()](https://react.dev/reference/react/useRef).

**JavaScript**

```js
const ref = React.useRef(null)
```

If you're using **TypeScript**:

You need to import:

```ts
import type { ICarouselInstance } from "react-native-reanimated-carousel";
```

and then:

```ts
const ref = React.useRef<ICarouselInstance>(null);
```

Now, you only need to pass the ref to the Carousel component:

```js
<Carousel ref={ref} (...) />;
```

And now you can use these methods throughout your component. Here's an example of implementing a button to go to the next slide:

```tsx
import React from "react";
import Carousel from "react-native-reanimated-carousel";
import type { ICarouselInstance } from "react-native-reanimated-carousel";
import { Button, Text, View } from "react-native";

// 1. Create a data array with the slides
const data = [
  {
    title: "Slide 1",
    content: "Slide 1 Content",
  },
  {
    title: "Slide 2",
    content: "Slide 2 Content",
  },
  {
    title: "Slide 3",
    content: "Slide 3 Content",
  },
];

const Example = () => {
  const ref = React.useRef<ICarouselInstance>(null); // 2. Create a ref for the Carousel component

  return (
    <View>
      {/* 3. Add the Carousel component with the ref */}
      <Carousel
        ref={ref}
        data={data}
        width={300} // 4. Add the required "width" prop
        renderItem={({ item }) => (
          <View>
            <Text>{item.title}</Text>
            <Text>{item.content}</Text>
          </View>
        )}
      />
      {/* 5. Add a button to trigger the next slide */}
      <Button
        title="Next"
        onPress={() => {
          ref.current?.next(); // 6. Call the "next" method on the ref
        }}
      />
    </View>
  );
};

export default Example;
```

### `prev`

Scroll to previous item, it takes one optional argument \(count\), which allows you to specify how many items to cross

| type   |
| ------ |
| \(\{ count: number, animated: boolean, onFinished?: \(\) => void \}\) \=\> void |

### `next`

Scroll to next item, it takes one optional argument \(count\), which allows you to specify how many items to cross

| type   |
| ------ |
| \(\{ count: number, animated: boolean, onFinished?: \(\) => void \}\) => void |

### `scrollTo`

```tsx copy
scrollTo({ count: -2 })
```

Use count to scroll to a position where relative to the current position, scrollTo\(\{count:-2\}\) is equivalent to prev\(2\), scrollTo\(\{count:2\}\) is equivalent to next\(2\). And also can jump to specific position.

| type   |
| ------ |
| \(\{ index: number, count: number, animated: boolean, onFinished\?: \(\) => void \}\) => void |

### `getCurrentIndex`

Get current item index

| type   |
| ------ |
| \(\)=>number |
